fix(docs): make the docs site readable to agents that fetch it - #34
Merged
Conversation
Agents pointed at the docs hit a client-rendered SPA: a wrong URL guess
(e.g. /docs) returns a 200 shell whose only text is "OpenIslands", with no
pointer to the plain-text docs that already exist (/llms.txt, /llms-full.txt,
per-page .md). And once on a .md page, its internal links pointed back at the
JS-rendered HTML routes, bouncing the agent out of markdown.
- __root.tsx: signpost the plain-text docs from the root (so a JS-less fetch
of any path, incl. the SPA fallback shell, finds them): a
rel="alternate" text/markdown link plus a <noscript> listing
/llms-full.txt, /llms.txt, the append-.md trick, and /start.md.
- source.ts: linkToMarkdownSiblings() rewrites internal absolute doc links to
their .md sibling (skips the root, asset files, and external links).
- {$}.md route: rewrite cross-links to .md and append a footer pointing at
/llms-full.txt and /llms.txt.
- llms.txt route: rewrite the index links to .md and prepend a note telling
the agent the .md suffix works for any page (per the llms.txt convention of
highlighting markdown versions).
Content negotiation (Accept: text/markdown on the same URL) is intentionally
not done — it needs a request-time server, and the docs deploy is assets-only
static. The .md suffix is the static-compatible equivalent.
This was referenced Jun 25, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
When an agent is pointed at OpenIslands and reaches for the docs, it hits a client-rendered SPA:
/introduction,/mcp, …), so a guessed URL like/docsmatches no prerendered page. The assets-only Cloudflare deploy answers any unmatched path with a 200 OK SPA shell whose only rendered text is "OpenIslands" — no content, no 404, no signpost./llms.txt,/llms-full.txt, per-page/<page>.md,/start.md) but nothing advertised them..mdpage, its internal links pointed back at the JS-rendered HTML routes, bouncing the agent out of markdown.Changes
__root.tsx— signpost the plain-text docs from the root, so a JS-less fetch of any path (including the SPA fallback shell) finds them: arel="alternate"text/markdownlink in<head>plus a<noscript>listing/llms-full.txt,/llms.txt, the append-.mdtrick, and/start.md.source.ts—linkToMarkdownSiblings()rewrites internal absolute doc links to their.mdsibling (skips the site root, asset files, and external links).{$}.mdroute — rewrite cross-links to.mdand append a footer pointing at/llms-full.txtand/llms.txt.llms.txtroute — rewrite the index links to.mdand prepend a note telling the agent the.mdsuffix works for any page it builds itself (per the llms.txt convention of highlighting markdown versions).Verified against the built output
introduction.md/getting-started.md: internal links →.md; external (http://…) and.txtresources untouched; footer present.llms.txt: note prepended, index links rewritten to.md._shell.html(the fallback for any wrong URL): carries therel="alternate"link +<noscript>pointer.Deliberately skipped
Content negotiation (
Accept: text/markdownon the same URL — what Mintlify does) needs a request-time server; the docs deploy is assets-only static, so there's no server to read the header. The.mdsuffix is the static-hosting-compatible equivalent and is already in place.pnpm build+pnpm typecheckclean; lint shows only pre-existing_splatwarnings.